<!-------- @HEADER
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 !  Zoltan Toolkit for Load-balancing, Partitioning, Ordering and Coloring
 !                  Copyright 2012 Sandia Corporation
 !
 ! Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
 ! the U.S. Government retains certain rights in this software.
 !
 ! Redistribution and use in source and binary forms, with or without
 ! modification, are permitted provided that the following conditions are
 ! met:
 !
 ! 1. Redistributions of source code must retain the above copyright
 ! notice, this list of conditions and the following disclaimer.
 !
 ! 2. Redistributions in binary form must reproduce the above copyright
 ! notice, this list of conditions and the following disclaimer in the
 ! documentation and/or other materials provided with the distribution.
 !
 ! 3. Neither the name of the Corporation nor the names of the
 ! contributors may be used to endorse or promote products derived from
 ! this software without specific prior written permission.
 !
 ! THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
 ! EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 ! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 ! PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
 ! CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 ! EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 ! PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 ! PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 ! LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 ! NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 ! SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 !
 ! Questions? Contact Karen Devine	kddevin@sandia.gov
 !                    Erik Boman	egboman@sandia.gov
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 ! @HEADER
-------> 
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="GENERATOR" content="Mozilla/4.7 [en] (X11; U; SunOS 5.7 sun4u) [Netscape]">
   <meta name="sandia.approved" content="SAND99-1376">
   <meta name="author" content="karen devine, kddevin@sandia.gov">
   <title> Zoltan Developer's Guide:  ZoltanTimer Utilities</title>

</head>
<body bgcolor="#FFFFFF">

<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_services_debug.html">Next</a>&nbsp; |&nbsp; <a href="dev_services_time.html">Previous</a></i></b></div>
<!------------------------------------------------------------------------->

<h2>
<a NAME="ZOLTANTIMER"></a>High-Level Timing Services:  ZOLTAN_TIMER</h2>
The ZOLTAN_TIMER provides high-level capability for instrumenting
code with timers and reporting the execution times measured.  
The ZOLTAN_TIMER can store many separate timers within a single 
ZOLTAN_TIMER object and associate a name with each timer for ease of
reporting.  It can perform parallel synchronization among processors 
using a time to ensure that all time is attributed to the correct section
of the timed code.  Its output contains the maximum, minimum and average
times over sets of processors.
<p>
The ZOLTAN_TIMER uses 
<b><a href="dev_services_time.html#Zoltan_Time">Zoltan_Time</a></b>
to obtain the current clock time.  
<p>
NOTE:  The current implementation of ZOLTAN_TIMER relies on two assumptions
to work correctly.  
<ol>
<li>
ZOLTAN_TIMER assumes that individual timers within a single
ZOLTAN_TIMER object are initialized in the same order on all processors. 
Times over multiple processors are accrued based on the value of the
<i>timer_idx</i> returned by <b><a href="#Init">Zoltan_Timer_Init</a></b>,
so for accurate timing,
each processor should associate the same value of <i>timer_idx</i> with
the same section of code.  
<p>
<li>
ZOLTAN_TIMER uses synchronization in
<b><a href="#Print">Zoltan_Timer_Print</a></b> and
<b><a href="#PrintAll">Zoltan_Timer_PrintAll</a></b>, and optionally in
<b><a href="#Start">ZOLTAN_TIMER_START</a></b> and 
<b><a href="#Stop">ZOLTAN_TIMER_STOP</a></b>.  For these routines to 
work properly, then, all processors must call them at the same place in
the code to satisfy the synchronization.  A possible workaround is to 
provide MPI_COMM_SELF as an argument to these functions for single-processor
timing.
</ol>
<p>
In future work, these constraints may be weakened so that, for instance,
different processors may have different numbers of timers or skip
synchronization points.
<p>
<p>
<hr>
<table>
<tr VALIGN=TOP>
<td WIDTH="50%">
<b>Source code location:</b>
</td>
<td WIDTH="50%">
<i>Utilities/Timer</i>
</td>
</tr>
<tr VALIGN=TOP>
<td>
<b>Function prototypes file:</b>
</td>
<td>
<i>Utilities/Timer/zoltan_timer.h</i> or <i>include/zoltan_timer.h</i>
<i>Utilities/Timer/zoltan_timer_cpp.h</i> or <i>include/zoltan_timer_cpp.h</i>
</td>
</tr>
<tr VALIGN=TOP>
<td>
<b>Library name:</b>
</td>
<td>
libzoltan_timer.a
</td>
</tr>
<tr VALIGN=TOP>
<td>
<b>Other libraries used by this library:</b>
</td>
<td>
libmpi.a and libzoltan_mem.a. 
</td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2">
<b>Routines:</b>
<blockquote>
  <a href="#Create">Zoltan_Timer_Create</a>:  Creates a ZOLTAN_TIMER object to store timers.<br>
  <a href="#Init">Zoltan_Timer_Init</a>:  Initializes a new timer.<br>
  <a href="#Start">ZOLTAN_TIMER_START</a>:  Starts a single timer.<br>
  <a href="#Stop">ZOLTAN_TIMER_STOP</a>:  Stops a single timer.<br>
  <a href="#Print">Zoltan_Timer_Print</a>:  Prints the values of a single timer.<br>
  <a href="#PrintAll">Zoltan_Timer_PrintAll</a>:  Prints the values of all timers.<br>
  <a href="#Reset">Zoltan_Timer_Reset</a>:  Resets a single timer.<br>
  <a href="#Copy">Zoltan_Timer_Copy</a>:  Copies a ZOLTAN_TIMER object to newly
allocated memory.<br>
  <a href="#CopyTo">Zoltan_Timer_Copy_To</a>:  Copies a ZOLTAN_TIMER object to existing memory.<br>
  <a href="#Destroy">Zoltan_Timer_Destroy</a>:  Frees a ZOLTAN_TIMER object.<br>
</blockquote>
</td>
</tr>
<tr VALIGN=TOP>
<td COLSPAN="2">
<b>Use in Zoltan:</b>
<blockquote>
The ZOLTAN_TIMER utilities are used in Zoltan's graph and hypergraph 
algorithms.  It is activated
by setting parameter <i>use_timers</i> to a positive integer value.
<p>
</blockquote>
</td>
</tr>
</table>

<!------------------------------------------------------------------------->
<hr>
<a NAME="Create"></a>
<hr>
<table width="100%">
<tr>
<td width="20%" valign=top>
C:
</td>
<td width="80%" valign=top>
struct Zoltan_Timer *<b>Zoltan_Timer_Create</b>(
int <i>timer_flag</i>);
</td>
</tr>
<tr>
<td valign=top>
C++:
</td>
<td valign=top>
<b>Zoltan_Timer_Object(int <i>timer_flag</i>);</b>
</td>
</tr>
</table>
<hr>
<b>Zoltan_Timer_Create</b> allocates memory for storing information to be
used by the Zoltan_Timer. The pointer returned by this function is passed
to many subsequent functions. An application or Zoltan itself
may allocate more than one
Zoltan_Timer data structure; for example, a separate Zoltan_Timer may be
used in different partitioning algorithms or in different routines.
<p>
In the C++ interface, the Zoltan_Timer_Object class represents a Zoltan_Timer 
data
structure and the functions that operate on it. It is the constructor that
allocates an instance of a Zoltan_Timer_Object. It has no return value. 
<p>
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Input Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp; timer_flag</i>
</td>
<td>
A flag indicating the type of timer to be used; it is passed to
calls to <b><a href="dev_services_time.html#Zoltan_Time">Zoltan_Time</a></b>.  
Valid values are
<i>ZOLTAN_TIME_WALL</i>, <i>ZOLTAN_TIME_CPU</i>, <i>ZOLTAN_TIME_USER</i>
and <i>ZOLTAN_TIME_DEF</i> (the default timer).  See the
<a href="dev_services_time.html">timing routines</a> for more information
about the timer_flag values.
</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; struct Zoltan_Timer *</td>

<td>
Pointer to memory for storage of Zoltan_Timer information. If an error occurs,
NULL will be returned in C.
</td>
</tr>
</table>

<p>

<!------------------------------------------------------------------------->
<hr>
<a NAME="Init"></a>
<hr>
<table width="100%">
<tr>
<td width="20%" valign=top>
C:
</td>
<td width="80%" valign=top>
int <b>Zoltan_Timer_Init</b>(
struct Zoltan_Timer *<i>zt</i>,
int <i>use_barrier</i>,
const char *<i>timer_name</i>
);
</td>
</tr>
<tr>
<td valign=top>
C++:
</td>
<td valign=top>
int <b>Zoltan_Timer_Object::Init</b>(
const int <i>use_barrier</i>,
const std::string & timer_name);
</td>
</tr>
</table>
<hr>
<b>Zoltan_Timer_Init</b> initializes a single timer within a Zoltan_Timer
object.  Each timer in the Zoltan_Timer object 
is assigned a unique integer, which is returned by
<b>Zoltan_Timer_Init</b> and is later used to indicate which timer to start or
stop.  It is also used to accrue times across multiple processors.
<b>Zoltan_Timer_Init</b> may be called several times with the 
same Zoltan_Timer object to create many different times within the object. 
<p>
Note that processors must initialize multiple timers within a Zoltan_Timer
object in the same order to
ensure that the returned timer index value is the same on each processor.
<p>
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Input Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>zt</i>
</td>
<td>
Pointer to the Zoltan_Timer struct returned by <b><a
href="#Create">Zoltan_Timer_Create</a></b>.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>use_barrier</i>
</td>
<td>
Flag indicating whether to synchronize processors before starting or
stopping a timer.  A value of 1 causes MPI_Barrier to be invoked before the
timer is started or stopped; a value of 0 provides no synchronization.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>timer_name</i>
</td>
<td>
A character string associated with the timer; it is printed as the timer
name in <b><a href="#Print">Zoltan_Timer_Print</a></b> and 
<b><a href="#PrintAll">Zoltan_Timer_PrintAll</a></b>.
</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; int</td>

<td>
The unique integer identifier for this timer.
</td>
</tr>
</table>

<!------------------------------------------------------------------------->
<hr>
<a NAME="Start"></a>
<hr>
<table width="100%">
<tr>
<td width="20%" valign=top>
C:
</td>
<td width="80%" valign=top>
int <b>ZOLTAN_TIMER_START</b>(
struct Zoltan_Timer *<i>zt</i>,
int <i>timer_idx</i>,
MPI_COMM <i>communicator</i>
);
</td>
</tr>
<tr>
<td valign=top>
C++:
</td>
<td valign=top>
int <b>Zoltan_Timer_Object::Start</b>(
const int <i>timer_idx</i>,
const MPI_COMM & communicator);
</td>
</tr>
</table>
<hr>
<b>ZOLTAN_TIMER_START</b> starts the timer with index <i>timer_idx</i>
associated with the Zoltan_Timer struct <i>zt</i>.  Error checking ensures
that the timer is not already running before it is started.  If the timer
timer_idx
was initialized with <i>use_barrier</i>=1, all processors should start
the timer at the same point in the code.
<p>
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Input Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>zt</i>
</td>
<td>
Pointer to the Zoltan_Timer struct returned by <b><a
href="#Create">Zoltan_Timer_Create</a></b>.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>timer_idx</i>
</td>
<td>
The integer timer index 
(returned by <b><a href="#Init">Zoltan_Timer_Init</a></b>)
of the timer to be started.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>communicator</i>
</td>
<td>
The MPI communicator to be used for synchronization is the timer was
initialized with <i>use_barrier</i>=1.
</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; int</td>

<td>
Error code indicating whether the timer started successfully.
</td>
</tr>
</table>

<!------------------------------------------------------------------------->
<hr>
<a NAME="Stop"></a>
<hr>
<table width="100%">
<tr>
<td width="20%" valign=top>
C:
</td>
<td width="80%" valign=top>
int <b>ZOLTAN_TIMER_STOP</b>(
struct Zoltan_Timer *<i>zt</i>,
int <i>timer_idx</i>,
MPI_COMM <i>communicator</i>
);
</td>
</tr>
<tr>
<td valign=top>
C++:
</td>
<td valign=top>
int <b>Zoltan_Timer_Object::Stop</b>(
const int <i>timer_idx</i>,
const MPI_COMM & communicator);
</td>
</tr>
</table>
<hr>
<b>ZOLTAN_TIMER_STOP</b> stops the timer with index <i>timer_idx</i>
associated with the Zoltan_Timer struct <i>zt</i>.  Error checking ensures
that the timer is already running before it is stopped.  If the timer
timer_idx
was initialized with <i>use_barrier</i>=1, all processors should stop
the timer at the same point in the code.
<p>
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Input Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>zt</i>
</td>
<td>
Pointer to the Zoltan_Timer struct returned by <b><a
href="#Create">Zoltan_Timer_Create</a></b>.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>timer_idx</i>
</td>
<td>
The integer timer index 
(returned by <b><a href="#Init">Zoltan_Timer_Init</a></b>)
of the timer to be stopped.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>communicator</i>
</td>
<td>
The MPI communicator to be used for synchronization is the timer was
initialized with <i>use_barrier</i>=1.
</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; int</td>

<td>
Error code indicating whether the timer stopped successfully.
</td>
</tr>
</table>
<!------------------------------------------------------------------------->
<hr>
<a NAME="Print"></a>
<hr>
<table width="100%">
<tr>
<td width="20%" valign=top>
C:
</td>
<td width="80%" valign=top>
int <b>Zoltan_Timer_Print</b>(
struct Zoltan_Timer *<i>zt</i>,
int <i>timer_idx</i>,
int <i>proc</i>,
MPI_Comm <i>comm</i>,
FILE *<i>fp</i>
);
</td>
</tr>
<tr>
<td valign=top>
C++:
</td>
<td valign=top>
int <b>Zoltan_Timer_Object::Print</b>(
const int <i>timer_idx</i>,
const int <i>proc</i>,
const MPI_Comm &<i>comm</i>,
FILE *<i>fp</i>
);
</td>
</tr>
</table>
<hr>
<b>Zoltan_Timer_Print</b> accrues accumulated times for a single timer
<i>timer_idx</i> across a communicator and computes the minimum, maximum and
average values across all processors of the MPI communicator <i>comm</i>.
These values, as well as the timer index <i>timer_idx</i> and timer name,
are then printed by processor <i>proc</i>.
Because of the synchronization needed to compute the minimum, maximum and
average values, <b>Zoltan_Timer_Print</b> must be called by all processors in
the communicator <i>comm</i>.  Communicator MPI_COMM_SELF can be used to print
a single processor's timer values.
<p>
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Input Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>zt</i>
</td>
<td>
Pointer to the Zoltan_Timer struct returned by <b><a
href="#Create">Zoltan_Timer_Create</a></b>.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>timer_idx</i>
</td>
<td>
The integer timer index 
(returned by <b><a href="#Init">Zoltan_Timer_Init</a></b>)
of the timer to be printed.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>proc</i>
</td>
<td>
The rank (within MPI communicator <i>comm</i>) of the processor that should
print the timer's values.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>comm</i>
</td>
<td>
The MPI communicator across which minimum, maximum and average values
of the timer should be computed.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>fp</i>
</td>
<td>
The file pointer to a open, writable file to which timer values 
should be printed.  
Special files <i>stdout</i>
and <i>stderr</i> are also legal values for this argument.
</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; int</td>

<td>
Error code.
</td>
</tr>
</table>

<!------------------------------------------------------------------------->
<hr>
<a NAME="PrintAll"></a>
<hr>
<table width="100%">
<tr>
<td width="20%" valign=top>
C:
</td>
<td width="80%" valign=top>
int <b>Zoltan_Timer_PrintAll</b>(
struct Zoltan_Timer *<i>zt</i>,
int <i>proc</i>,
MPI_Comm <i>comm</i>,
FILE *<i>fp</i>
);
</td>
</tr>
<tr>
<td valign=top>
C++:
</td>
<td valign=top>
int <b>Zoltan_Timer_Object::PrintAll</b>(
const int <i>proc</i>,
const MPI_Comm &<i>comm</i>,
FILE *<i>fp</i>
);
</td>
</tr>
</table>
<hr>
<b>Zoltan_Timer_PrintAll</b> accrues accumulated times for all timers
in <i>zt</i> across a communicator and computes the minimum, maximum and
average values across all processors of the MPI communicator <i>comm</i>.
The timer values for each timer, as well as its timer index  and timer name,
are then printed by processor <i>proc</i>.
Because of the synchronization needed to compute the minimum, maximum and
average values, <b>Zoltan_Timer_PrintAll</b> must be called by all processors in
the communicator <i>comm</i>.  Communicator MPI_COMM_SELF can be used to print
a single processor's timer values.
<p>
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Input Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>zt</i>
</td>
<td>
Pointer to the Zoltan_Timer struct returned by <b><a
href="#Create">Zoltan_Timer_Create</a></b>.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>proc</i>
</td>
<td>
The rank (within MPI communicator <i>comm</i>) of the processor that should
print the timer's values.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>comm</i>
</td>
<td>
The MPI communicator across which minimum, maximum and average values
of the timer should be computed.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>fp</i>
</td>
<td>
The file pointer to a open, writable file to which timer values 
should be printed.  
Special files <i>stdout</i>
and <i>stderr</i> are also legal values for this argument.
</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; int</td>

<td>
Error code.
</td>
</tr>
</table>

<!------------------------------------------------------------------------->
<hr>
<a NAME="Reset"></a>
<hr>
<table width="100%">
<tr>
<td width="20%" valign=top>
C:
</td>
<td width="80%" valign=top>
int <b>Zoltan_Timer_Reset</b>(
struct Zoltan_Timer *<i>zt</i>,
int <i>timer_idx</i>,
int <i>use_barrier</i>,
const char *<i>timer_name</i>
);
</td>
</tr>
<tr>
<td valign=top>
C++:
</td>
<td valign=top>
int <b>Zoltan_Timer_Object::Reset</b>(
const int <i>timer_idx</i>,
const int <i>use_barrier</i>,
const std::string & timer_name);
</td>
</tr>
</table>
<hr>
<b>Zoltan_Timer_Reset</b> resets the single timer represented by
<i>timer_idx</i> within a Zoltan_Timer
object. The accumulated time within the timer is reset to zero.
The timer's name <i>timer_name</i> and the flag <i>use_barrier</i>
indicating whether the
timer should be started and stopped synchronously across processors
may be changed as well.
<p>
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Input Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>zt</i>
</td>
<td>
Pointer to the Zoltan_Timer struct returned by <b><a
href="#Create">Zoltan_Timer_Create</a></b>.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>timer_idx</i>
</td>
<td>
The integer timer index 
(returned by <b><a href="#Init">Zoltan_Timer_Init</a></b>)
of the timer to be reset.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>use_barrier</i>
</td>
<td>
Flag indicating whether to synchronize processors before starting or
stopping a timer.  A value of 1 causes MPI_Barrier to be invoked before the
timer is started or stopped; a value of 0 provides no synchronization.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>timer_name</i>
</td>
<td>
A character string associated with the timer; it is printed as the timer
name in <b><a href="#Print">Zoltan_Timer_Print</a></b> and 
<b><a href="#PrintAll">Zoltan_Timer_PrintAll</a></b>.
</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; int</td>

<td>
Error code indicating whether or not the timer was reset correctly.
</td>
</tr>
</table>

<!------------------------------------------------------------------------->
<hr>
<a NAME="Copy"></a>
<hr>
<table width="100%">
<tr>
<td width="20%" valign=top>
C:
</td>
<td width="80%" valign=top>
struct Zoltan_Timer *<b>Zoltan_Timer_Copy</b>(
struct Zoltan_Timer *<i>from</i>);
</td>
</tr>
<tr>
<td valign=top>
C++:
</td>
<td valign=top>
<b>Zoltan_Timer_Object</b>(const Zoltan_Timer_Object &<i>from</i>);
</td>
</tr>
</table>
<hr>
<b>Zoltan_Timer_Copy</b> creates a new ZOLTAN_TIMER object and copies the
state of the existing ZOLTAN_TIMER object <i>from</i> to the new object.  
It returns the new ZOLTAN_TIMER object.
<p>
In C++, there is no direct interface to <b>Zoltan_Timer_Copy</b>.
Instead, the Zoltan_Timer_Object copy constructor invokes the C library
function <b>Zoltan_Timer_Copy</b>.
<p>
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Input Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>from</i>
</td>
<td>
Pointer to the Zoltan_Timer struct returned by <b><a
href="#Create">Zoltan_Timer_Create</a></b> whose state is to be copied to
new memory.
</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; struct Zoltan_Timer *</td>

<td>
Pointer to memory for storage of the copied Zoltan_Timer information. 
If an error occurs, NULL will be returned in C.
</td>
</tr>
</table>


<!------------------------------------------------------------------------->
<hr>
<a NAME="CopyTo"></a>
<hr>
<table width="100%">
<tr>
<td width="20%" valign=top>
C:
</td>
<td width="80%" valign=top>
int <b>Zoltan_Timer_Copy_To</b>(
struct Zoltan_Timer **<i>to</i>,
struct Zoltan_Timer *<i>from</i>
);
</td>
</tr>
<tr>
<td valign=top>
C++:
</td>
<td valign=top>
<b>Zoltan_Timer_Object</b> & operator =(const Zoltan_Timer_Object &<i>from</i>);
</td>
</tr>
</table>
<hr>
<b>Zoltan_Timer_Copy_To</b> copies one ZOLTAN_TIMER object to another, after
first freeing any memory used by the targe ZOLTAN_TIMER object and 
re-initilizing it.
<p>
The C++ interface to <b>Zoltan_Timer_Copy_To</b> is through the
Zoltan_Timer_Object copy operator
which invokes the C library
function <b>Zoltan_Timer_Copy_To</b>.
<p>
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>to</i>
</td>
<td>
Pointer to the Zoltan_Timer struct 
whose state is to be overwritten with the state of <i>from</i>.
</td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>from</i>
</td>
<td>
Pointer to the Zoltan_Timer struct returned by <b><a
href="#Create">Zoltan_Timer_Create</a></b> whose state is to be copied to
<i>to</i>.
</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; int</td>

<td>
Error code.
</td>
</tr>
</table>

<!------------------------------------------------------------------------->
<hr>
<a NAME="Destroy"></a>
<hr>
<table width="100%">
<tr>
<td width="20%" valign=top>
C:
</td>
<td width="80%" valign=top>
void <b>Zoltan_Timer_Destroy</b>(
struct Zoltan_Timer **<i>zt</i>);
</td>
</tr>
<tr>
<td valign=top>
C++:
</td>
<td valign=top>
<b>~Zoltan_Timer_Object();</b>
</td>
</tr>
</table>
<hr>
<b>Zoltan_Timer_Destroy</b> frees memory allocated by 
<a href="#Create"><b>Zoltan_Timer_Create</b></a> and in C, sets the 
timer pointer <i>zt</i> to NULL.  <b>Zoltan_Timer_Destroy</b> should be
called when an application is finished using a timer object.
<p>
In C++, the Zoltan_Timer_Object class represents a Zoltan_Timer 
data
structure and the functions that operate on it.  <b>Zoltan_Timer_Destroy</b>
is called by the
destructor for the Zoltan_Timer_Object.
<p>
<table WIDTH="100%" >
<tr VALIGN=TOP>
<td VALIGN=TOP WIDTH="20%"><b>Input Arguments:</b></td>

<td WIDTH="80%"></td>
</tr>

<tr>
<td VALIGN=TOP><i>&nbsp;&nbsp;&nbsp;<i>zt</i>
</td>
<td>
Pointer to the pointer to the Zoltan_Timer struct returned by <b><a
href="#Create">Zoltan_Timer_Create</a></b>.  Upon return, zt is set to NULL.
</td>
</tr>

<tr>
<td><b>Returned Value:</b></td>

<td></td>
</tr>

<tr>
<td VALIGN=TOP>&nbsp;&nbsp; None. </td>

<td>
</td>
</tr>
</table>

<p>

<!------------------------------------------------------------------------->
<p>

<hr WIDTH="100%">
<br>[<a href="ug.html">Table of Contents</a>&nbsp; |&nbsp; <a href="dev_services_debug.html">Next:&nbsp;
Debugging Services</a>&nbsp; |&nbsp; <a href="dev_services_time.html">Previous:&nbsp;
Timing Routines</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>
